freecivfandomcom-20200223-history
Requirements
Requirements are elementary rules of Freeciv ruleset. Each of them represents a statement that can be true, false, or sometimes undefined (that can be resolved to either true or false in specific cases). Requirements typically are bundled into requirement vectors that represent complex statements that are true if and only if each requirement inside them is true (with an exception of nreqs vectors in v.2.4 that have "or" logical operation, but they are negated overall). These vectors are found in effects, action enablers, disaster causes and other elements of the ruleset. Elements of a requirement type The property of something that is checked, e.g. wether we are interested in a number of units on a tile, an extra on it, its owning player etc. range Kind of target we are checking, e.g. a player, a city, any city trading with a city, or the whole world. Ranges are limited for specific requirement types and targets (e.g. you can't get DiplRel of a continent). For terrain-specific requirements accepting "City"/"Traderoute" range, the city/cities working map is iterated over. name Not necessarily something you would call "name", but a value of the property for the target. Flags ;survives:The requirement is met even after the target (must be a wonder) is destroyed. ;quiet:Do not generate automatic help for the requirement. ;present (2.6+)/negated (2.5):Wether the requirement value should be negated. Example of a requirement vector Consider a definition of an effect: effect_hydro_plant name = "Output_Bonus" value = 25 reqs = {"type", "name", "range" "Building", "Factory", "City" "Building", "Hydro Plant", "City" "OutputType", "Shield", "Local" } Here reqs is the requirement vector for the effect. First line lists the elements of the requirement, and all the other lines list their values in the same order. The flags are optional and can be omitted from the header line if they are never set in the vector ("survives", "quiet" and (2.5 only) "negated" default to FALSE and "present" (2.6 and later) to TRUE) and from any value line where they are default. The requirements tell that the effect of increasing output on 25 % happens in cities where there are buildings Factory and HydroPlant for Shield-type output. Programming realization Requirements are described in common/requirements.ch. Each requirement is stored in struct requirement which contains, among others, struct universal source field in which the effect's type and name are stored; possible types are listed in specenum universals_n (VUT_...) (in common/fc_types.h) while possible ranges are in req_range (REQ_RANGE_...). The main function that calculates a requirement (redirecting necessary information to a function appropriate for specific requirement type and range) is is_req_active(const struct player *target_player, // Player and upper ranges const struct player *other_player, // To whom calculate DiplRel at Local range const struct city *target_city, // City and base of Traderoute range const struct impr_type *target_building, const struct tile *target_tile,// All the rest is referred as "Local" range const struct unit *target_unit, const struct unit_type *target_unittype,// If not specified, calculated from target_unit const struct output_type *target_output,// shields/science/etc. const struct specialist *target_specialist, const struct action *target_action,//new in 3.0 const struct requirement *req,// The requirement itself const enum req_problem_type prob_type)// Wether resolve uncertainity to true or false This function is usually called through are_reqs_active() that has the same parameters except being applied to a vector of requirements that are tested in order (it had been suggested to reorder them for optimisation but that is not actually done). When and how the parameters are filled can be seen from certain places of the code; there are multiple wrapping functions to call this one that mask irrelevant parameters. For World-range effects, all parameters are NULLs. Effects for units use as a city parameter the city where the unit is situated now or is being built, if any; requirements defined for terrain extras mostly ignore the city. Effects generally don't fill other_player ("Illegal_Action_Move_Cost" is among the exceptions) while action enablers use target player for the actor reqs and actor player for the target reqs, and extras' reqs supply tile owner as it. Requirement vectors have some additional restrictions that block loading senseless rules (e.g. requiring both terrain and terrain class, or two min-same-thing requirements), that is handled in server/rssanity.c. The text that is added to automatic help for game objects for non-quiet requirements is defined in common/reqtext.c. See also Category:Editing rulesets